Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/480.lha/SmartField/Docs/Structure Definitions.pp/Structure Definitions

Text File | 1991-02-11 | 19.1 KB | 451 lines

STRUCTURE DEFINITIONS


struct Field
------------

This is the structure which all fields use.  It has the following format:

    struct Field {
        struct Field *PrevField;
        struct Field *NextField;
        UBYTE  *Buffer;
        UBYTE  *UndoBuffer;
        UBYTE  *DupBuffer;
        UBYTE  FrontPen;
        UBYTE  BackPen;
        UBYTE  Style;
        UBYTE  Enabled;
        struct FieldMask *Mask;
        USHORT Flags;
        SHORT  Left;
        SHORT  Top;
        SHORT  Right;
        SHORT  Bottom;
        SHORT  MaxChars;
        SHORT  NumChars;
        SHORT  DispChars;
        SHORT  BufferPos;
        SHORT  DispPos;
        struct IntuiText *FieldTitle;
        struct Border *FieldBorder;
        struct Image *FieldImage;
        SHORT  FieldID;
        APTR   UserPtr;
        LONG   Reserved1;
        LONG   Reserved2;
    };

    The individual elements are defined as follows:

    struct Field *PrevField

        This is a pointer to the previous field in your field list.  Perhaps
        the easiest way to set up field lists is to pre-initialize them as
        global variables so that all routines in your program may access
        them.  Unlike Intuition gadgets which should be defined in reverse
        order so that the NextGadget pointer points to an already defined
        gadget, you should define the fields in the order of cursor travel,
        linking them together with the PrevField pointer.  Of course, the
        PrevField pointer for the first field in the list should be set to
        NULL.  Then before you display the fields, you should call the
        field_link() function to set the NextField pointers.  If you open
        your field devices with the field_open() function, however, this is
        done for you.

    struct Field *NextField

        This is a pointer to the next field in your field list.  If you are
        pre-initializing your fields, set this field to LATER (which is
        defined in toolkit/toolkit.h as NULL) for all fields except the final
        field which can be set to NULL.  This field is then filled in when
        you call the field_link() or field_open() functions.  Because many of
        the SmartFields functions access this pointer, be sure to set this
        parameter immediately.

    UBYTE *Buffer

        This is a pointer to the null-terminated string which will hold the
        contents of the field.  It should be defined to be at least as large
        as MaxChars to prevent the overwriting of succeeding locations in
        memory.  All functions (except the field_reshow() function) expect
        this buffer to exist and will crash if this pointer is invalid.

    UBYTE *UndoBuffer

        This is a pointer to a null-terminated string which will hold the
        "undo" contents of the field.  The contents of a field are copied
        into its undo buffer when the cursor first appears in the field or if
        the contents of the field are deleted with the field_delete()
        function.  The contents of this buffer are then replaced into the
        field when the field_restore() function is called.  This buffer does
        not have to be defined, but if it is, it should be defined to be at
        least as large as MaxChars to prevent the overwriting of succeeding
        locations in memory.  If you do not wish to provide an UndoBuffer,
        set this pointer to NULL.  Then if a user invokes a command which
        would require an UndoBuffer (such as CTRL-X and CTRL-R), the screen
        will flash indicating that the buffer does not exist.  Because only
        one field at a time may be active, you may supply a single undo
        buffer for multiple fields.  The buffer must be defined to be at
        least as large as the largest MaxChars value in any of the fields
        using this buffer.  Because providing a single undo buffer for many
        fields can confuse the user, this method is not recommended.

    UBYTE *DupBuffer

        This is a pointer to a null-terminated string which will hold the
        contents of the field after the field has been cleared by the
        field_clear() function.  Then upon invocation of the field_dup()
        function, the contents of this buffer will be copied into the field.
        This buffer does not have to be defined, but if it is, it should be
        defined to be at least as large as MaxChars to prevent the
        overwriting of succeeding locations in memory.  If you do not wish to
        provide a DupBuffer, set this pointer to NULL.  Then if a user
        invokes the dup command (CTRL-D) which requires the DupBuffer, the
        screen will flash indicating that the buffer does not exist.

    UBYTE FrontPen

        This is the foreground color of the field characters.  This has
        nothing to do with the color of the text in the field title which you
        specify in the IntuiText structure, however.  The FrontPen can be any
        value from 0 to 7, and other values may produce strange results.
        Only values 0 through 3 are valid for fields in windows rendered in
        the Workbench screen.  These values represent the colors blue, white,
        black, and orange, respectively, with the default Workbench settings.

    UBYTE BackPen

        This is the color of the background of the field characters.  This
        parameter must have the same values as listed above for the FrontPen.
        Note that if the FrontPen and BackPen are equal, the field text will
        be invisible.  If you set the BackPen equal to a color other than the
        background color of the window, the field_clear() function renders a
        square the size of the input field in the BackPen color.  Use the
        graphic rendition test program to view this effect.

    UBYTE Style

        This is the style of the field text.  Use the flags as defined in
        console/console.h:  CON_PLAIN, CON_BOLD, CON_ITALIC, CON_UNDERSCORE,
        CON_INVERSE.  You can also OR the flags to produce a combined effect.
        For example:  CON_ITALIC | CON_UNDERSCORE will create an underlined-
        italic style.

    UBYTE Enabled

        This flag determines whether input is accepted into this field.  Use
        the FIELD_ENABLED and FIELD_DISABLED flags as defined in console/
        fields.h to provide for upward compatibility.  Do not change this
        flag manually.  Instead, use the field_disable() and field_enable()
        functions.

    struct FieldMask *Mask

        This is a pointer to the input mask for the field.  See the FieldMask
        structure definition for more information.  If this is set to NULL,
        then no input checking is done and all input characters are accepted.

    USHORT Flags

        This field is not used at this time, but was provided for future use.
        For upward compatibility, set this field to 0 and do not modify it.

    SHORT Left, Top

        These contain the horizontal and vertical window pixels of the upper
        left corner of the first character in the field.  See the "Field
        Layout" section for more information.

    SHORT Right, Bottom

        These contain the calculated horizontal and vertical pixels of the
        bottom right end of the field.  You may initialize these values to
        zero because the field_refresh() function calculates these based on
        the maximum number of characters allowed in the field and the size of
        each character according to the tf_XSize and tf_YSize parameters
        contained in the IFont structure pointed to in the Window structure.

    SHORT MaxChars

        This is the maximum number of characters including the terminal null
        that may be input into this field.  Thus, there will be no more that
        MaxChars-1 characters visible in the field at any time.  Be sure to
        define all buffers used by this field to be at least MaxChars long.
        Once set for a field, this value should not be modified until the
        field is removed from the window.

    SHORT NumChars

        This is the current number of characters in the field's buffer not
        including the terminal null.  Thus, this value will always be less
        than MaxChars (because MaxChars will always be at least one character
        larger because of the terminal null).  Do not modify this value in
        the calling program.  If you wish to change the contents of a field,
        change the contents of the Buffer, then call the field_redisplay()
        function.

    SHORT DispChars

        This is the number of characters currently visible in the field.
        This is not currently used but was provided for upward compatibility.
        Initialize this parameter to zero and do not modify it.

    SHORT BufferPos

        This is the current cursor position in the Buffer of the field.  Note
        that the first character in the field occupies BufferPos zero
        (because the buffer is a string).  A value does not imply that the
        field is currently active.  The currently active field is pointed to
        by the CurrentField parameter in the FieldHeader structure.  The
        BufferPos value is stored even after the cursor has left this field
        so that when the cursor returns, it will return to the exact position
        it was in when it left.  Warning: do not modify this value.  Use one
        of the cursor positioning functions instead.

    SHORT DispPos

        This parameter is not currently used but was provided for upward
        compatibility.  Initialize this parameter to zero and do not modify
        it.

    struct IntuiText *FieldTitle

        This is a pointer to an IntuiText structure which will be displayed
        as the field title by the field_refresh() function.  If you wish no
        title, set this pointer to NULL.  If you desire more than one title,
        link the text together using the NextText pointer in the Intuitext
        structure.  The text will be rendered in reference to the Left and
        Top edges of the field.

    struct FieldBorder *FieldBorder

        This is a pointer to a Border structure which will be rendered in
        reference to the Left and Top edges of the field.  If you do not want
        a border, set this pointer to NULL.  If you want more than one
        border, link the borders together using the NextBorder pointer in the
        Border structure.

    struct Image *FieldImage

        This is a pointer to an Image structure which will be rendered in the
        window's rastport in reference to the Left and Top edges of the
        field.  If you do not want an image, set this pointer to NULL.  If
        you want more than one image, link the images together using the
        NextImage pointer in the Image structure.  The field_refresh()
        function renders the field in the following order:  images, borders,
        title, field text.

    SHORT FieldID

        This field is provided for your own use to label and identify the
        fields.  The most common use of this field is in switch statements.
        This parameter is ignored by SmartFields.

    APTR UserPtr

        This is a pointer provided for your own use.  This parameter is
        ignored by SmartFields.

    LONG Reserved1, Reserved2

        These parameters were provided for future expansion.  Initialize
        these parameters to zero and do not modify them.


struct FieldHeader
------------------

This structure should be globally defined in your calling program, one
structure for each set of fields in a window.  Note that you can have
multiple sets (lists) of fields for each window (although only one is
recommended), but you can have only one window per field list.  If you elect
to open the devices required for console use yourself, be sure to place their
pointers in this structure so that the SmartFields functions can use them.
The FieldHeader structure has the following format:

    struct FieldHeader {
        struct Window *Window;
        struct MsgPort *WritePort;
        struct IOStdReq *WriteReq;
        struct MsgPort *ReadPort;
        struct IOStdReq *ReadReq;
        LONG   ConsoleError;
        UBYTE  *Buffer;
        struct FieldMask *Mask;
        SHORT  TypeMode;
        APTR   UserPtr;
        LONG   Reserved1;
        LONG   Reserved2;
        struct Field *FirstField;
        struct Field *FinalField;
        struct Field *CurrentField;
        SHORT  BufferPos;
    };

    The individual elements are defined as follows:

    struct Window *Window

        This is a pointer to the window containing the fields.  Note that you
        cannot link fields from different windows in the same list.  It is
        the responsibility of your calling program to open and close the
        window.

    struct MsgPort *WritePort
    struct IOStdReq *WriteReq
    struct MsgPort *ReadPort
    struct IOStdReq *ReadReq

        These are the message ports and read/write requests that need to be
        set up for the window's console device.  This is all handled by the
        field_open() and field_close() functions if you wish to let
        SmartFields do the dirty work for you.  The field_open() function
        sets these values to NULL then attempts to open each one.  The
        field_close() function then attempts to close each device with a non-
        zero pointer.

    LONG ConsoleError

        This is a flag containing the success of opening the console device
        for the window.  If the device could not be opened or has not been
        opened, it will contain the value of CONSOLE_ERROR as defined in
        console/console.h.  The field_open() and field_close() functions will
        open and close the console device if you choose.

    UBYTE *Buffer

        This is a pointer to the buffer which is used for console input.  It
        is the responsibility of the calling program to declare a buffer of
        at least CONSOLE_BUFFER_SIZE as defined in console/console.h to be
        used by the SmartFields program.  This buffer is handy because you
        can also use it for any other function in your calling program that
        needs a very temporary buffer.  By "very" we mean that any call to a
        SmartFields function may trash its contents.

    struct FieldMask *Mask

        This is a pointer to the input mask used by the console_input()
        function to filter input.  See the FieldMask structure definition for
        more information.  If you specify NULL for this parameter, no input
        checking will be done and all console input will be accepted.  If you
        wish to mask out input for individual fields, use the Mask parameter
        in the Field structure.

    SHORT TypeMode

        This is the current type mode, either INSERT_TYPE_MODE or
        TYPEOVER_TYPE_MODE as defined in console/console.h.  In Insert type
        mode, all characters you type are inserted in the field at the
        current cursor position, and all characters at and to the right of
        the cursor are moved one character position to the right to make room
        for the character typed.  The cursor does not move.  If you attempt
        to type in a field that is full, the screen will flash indicating
        that there is no more room to insert characters.  This is the mode
        that the Intuition string gadgets use.  In typeover mode, however,
        all characters you type replace the character under the cursor, and
        the cursor moves one character position to the right.  If the field
        is full, the character you type just replaces the final character in
        the field.  This is initialized for you by the field_open() function.

    APTR UserPtr

        This is a pointer provided for your own use and is ignored by
        SmartFields.

    LONG Reserved1, Reserved2

        These variables are provided for future expansion.

    struct Field *FirstField

        This contains a pointer to the first field in the field list.  This
        is automatically filled in by the field_open() function.

    struct Field *FinalField

        This contains a pointer to the final field in the field list.

    struct Field *CurrentField

        This contains a pointer to the current field in the field list.  If
        there is no current field, then this pointer will be NULL.

    SHORT BufferPos

        This is a storage variable used to pass values between the
        field_click() function and your calling program.  See the
        field_click() function description for more information on its use.


struct FieldMask
----------------

This structure is used by the field_input() function to determine if the
character typed is accepted in the current field.  You define a FieldMask
structure for each field in which you wish to restrict input.  Normally a
field will accept any displayable character as input.  If you wish to
restrict the field's input in any way, for example limiting it to only
alphabetic or numeric characters, you would define a FieldMask structure for
that field and set the Mask parameter of the field's Field structure equal to
the address of the mask you create.  More than one field may share the same
mask.  The FieldMask structure has the following format:

    struct FieldMask {
        ULONG Element[MASK_ELEMENTS];
    };

MASK_ELEMENTS is defined in console/field.h as 8.  Thus there are 8 long
integers of 32-bits each or 256 total bits in the FieldMask structure, which
just happens to correspond to the number of ASCII characters.  While it is
true that not all 256 ASCII characters are displayable, having this format
allows the mask creation and verification functions to use bit shifts instead
of time-consuming multiplication and division.

Upon user input, the field_input() function checks to see if the current
field has a mask.  If it does, it checks whether the bit in the mask
corresponding to the character input has been set to 1.  If it has (and there
is room for the character in the field), the character is placed in the
field.  If the corresponding bit is set to zero, then the screen will flash.
Note that this applies only to displayable characters and not to any control
code or function key.

This structure can also be used by the console_input() function to restrict
all console input.  You define a FieldMask structure and record its address
in the Mask parameter of either the FieldHeader or ConsoleHeader structure
(depending on which structure you are using).


struct ConsoleHeader
--------------------

The elements have the same meaning as in the FieldHeader structure.  They
have the following format:

    struct ConsoleHeader {
        struct Window *Window;
        struct MsgPort *WritePort;
        struct IOStdReq *WriteReq;
        struct MsgPort *ReadPort;
        struct IOStdReq *ReadReq;
        LONG   ConsoleError;
        UBYTE  *Buffer;
        struct FieldMask *Mask;
        SHORT  TypeMode;
        APTR   UserPtr;
        LONG   Reserved1;
        LONG   Reserved2;
    };

Notice that the ConsoleHeader structure is actually a subset of the
FieldHeader structure.  This means that you can pass a pointer to a
FieldHeader structure to any SmartFields function that is expecting a pointer
to a ConsoleHeader structure (but NOT vice-versa).


Structure Definitions  01/13/90
© Copyright 1990 Timm Martin
All Rights Reserved Worldwide

/*-- END --*/